-
Notifications
You must be signed in to change notification settings - Fork 4
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Reserved Keywords document #45
Conversation
332352d
to
bb588f7
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good overall. I like the idea of including this document on the partiql.org website. It can definitely be easier to find if we list it there. Left some minor comments and a question about creating different versions of this doc for different PartiQL versions/implementations.
docs/reserved-keywords.adoc
Outdated
== Reserved Keywords | ||
[NOTE] | ||
==== | ||
Reserved Keywords are yet to be https://github.com/partiql/partiql-spec/issues/2[formally defined] in PartiQL Specification, therefore there may be some differences in different PartiQL implementations. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it could be helpful to make a version of this document for each PartiQL version and implementation listing the reserved keywords (at least the versions with differences).
This can be useful as PartiQL versions change and develop over time. I know we've had similar questions related to our builtin functions (e.g. does partiql-lang-kotlin-x.y.z support this builtin function?).
For reference Microsoft's SQL server has different pages for their different versions:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think putting two additional dimensions (i.e., implementation and version) brings too much overhead unless we have a clear spec. definition for this. I see this document's objective to give a general list of possible keywords and a way to escape them while mentioning that the actual keywords can be different.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps a good compromise is adding PartiQL Spec. Version?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree that it could add overhead. I still think we should document somewhere though each implementation + implementation version's reserved keywords since they may change and add more keywords over time. Perhaps for each implementation we can have a doc listing the reserved keywords. As we perform new tagged releases on GitHub, we'll then have a link to the reserved keywords of that specific PartiQL version.
E.g. if we had a document called reserved-keywords.adoc in partiql-lang-kotlin, we could reference it like:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I generally agree, but I think we need to automate this using the Grammar in the code.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps we could add an issue for each implementation to
- make a reserved keywords doc listing all the reserved keywords
- have some way to automate this doc?
I think it can still be helpful to have the reserved keywords of each implementation/version visible
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just reflecting the offline response:
I think the following note should be sufficient:
Reserved keywords are yet to be https://github.com/partiql/partiql-spec/issues/2[formally defined] in PartiQL Specification, therefore there may be some differences in different PartiQL implementations.
I’m hesitant to go to a lower level b/c that increases the likelihood of exposing stale information if for example, Rust grammar changes.
I still think we need a story around versioned docs for implementations though and I’m going to open an issue for that.
Will update this thread with the issue.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Here is the issue for tracking the version-based documentation:
#46
Co-authored-by: Alan Cai <caialan@amazon.com>
docs/reserved-keywords.adoc
Outdated
== Reserved Keywords | ||
[NOTE] | ||
==== | ||
Reserved Keywords are yet to be https://github.com/partiql/partiql-spec/issues/2[formally defined] in PartiQL Specification, therefore there may be some differences in different PartiQL implementations. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree that it could add overhead. I still think we should document somewhere though each implementation + implementation version's reserved keywords since they may change and add more keywords over time. Perhaps for each implementation we can have a doc listing the reserved keywords. As we perform new tagged releases on GitHub, we'll then have a link to the reserved keywords of that specific PartiQL version.
E.g. if we had a document called reserved-keywords.adoc in partiql-lang-kotlin, we could reference it like:
= PartiQL Reserved Keywords | ||
|
||
The PartiQL language uses reserved keywords to parse and understand PartiQL statements. | ||
PartiQL Language Grammar Reserved Keywords cannot be used in PartiQL statements as-is. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Reserved Keywords" -- no need to capitalize, I'd think (the previous line doesn't).
"cannot be used in PartiQL statements as-is" --> "cannot be used as non-delimited identifiers". That's what a keyword means commonly. "Delimited" rather than "quoted" is the SQL terminology, I believe, but that's secondary.
Style-wise, 4 occurrences of "PartiQL" in 2 lines is a bit much. :-)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Style-wise, 4 occurrences of "PartiQL" in 2 lines is a bit much. :-)
Yep, tbh it was intentional to add some SEO twist to it as this will be in the website :)
Let me see if I can tone it down a bit.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, with SEO in the picture, I wash my hands. :-)
Description of changes:
Add Reserved Keywords document; it's in
adoc
so that it can be used in partiql.org.Rendered Page
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.